User Interface : Using the ApplicationBar Control

1. Problem

You need to add the application bar to your application.

2. Solution

You have to add an ApplicationBar section to the XAML of your page provided by PhoneApplicationPage within the phone namespace. Within this new tag, you can include one or more ApplicationBar tags provided—this time—by the shell namespace. The code generated by Visual Studio already contains a commented section in which ApplicationBar is defined with some buttons and menu items. You can simply uncomment and customize the code to obtain your goal.

3. How It Works

ApplicationBar is a Windows Phone control added to Silverlight just for Windows Phone devices. It allows you to have a sort of toolbar and menu in the application. The application bar is completely managed by the operating system, so it is placed at the bottom of the page when the application is in Portrait mode, and moved to one side when the phone is put in Landscape mode (which side depends on the direction in which you rotate your phone).

The application bar should contain at least four icons, and you should use the ones provided with the SDK. In the %Program Files%\Microsoft SDKs\Windows Phone\v7.0\Icons path, you can find both dark and light versions of application bar icons. You should use different icon colors depending on the selected theme . If you use the dark version, the operating system will take care of changing the icon colors for you, automatically. If you don't find the icon you need, you can use Microsoft Expression Blend for Windows Phone to draw your own.

The application bar also can contain menu items that will be shown when the user selects the ellipses at the top-right of the bar. You should not specify too many menu items, however, because the application bar will expand toward the top to show all items and could cover important parts of the user interface control. The official documentation sets this limit to at most five menu items. You have to set the IsMenuEnabled property to true to enable menu items in the application bar (see Figure 1 for the class diagram).

Figure 1. The ApplicationBar class diagram

The ApplicationBar control has the Opacity property, which affects the rectangle that contains the icons, not the icons themselves.. This property accepts a decimal value between 0 and 1. When you set this property to 1, the frame resizes the page's content in order to reserve space for the application bar. On the other hand, when you set this property to a value less than 1, the application bar and its buttons will be drawn over the page content.

The IsVisible property is used to set when the application bar has to be shown (true) and when it does not (false).

Although you can assign a name to both menu items and application bar buttons, you can't use those names to access related properties. You have to use the ButtonsMenuItems collections provided as properties by the ApplicationBar class to retrieve a reference to those buttons and menu items. Usually, you can and use the page class constructor to map application bar items to relative names.

As already said, ApplicationBar can contain both ApplicationBarIconButton and ApplicationBarMenuItem controls. ApplicationBarIconButton has some interesting properties, such as IconUri, which specifies the URI relative to a path where the image is stored.

The Text property is used to specify a very short button's description that will be shown when the user selects the ellipses button. Finally, IsEnabled is used to either enable or disable the button. ApplicationBarMenuItem uses the Text property to specify the menu item text that will be shown when the user displays the application bar by clicking the ellipses button.

4. The Code

To demonstrate this recipe, we are implementing the ApplicationBar in the 7Drum application, specifically in the Training page. This page allows you to add, edit, and delete an exercise.

In the Training.xaml page, you define an ApplicationBar control with four buttons and one menu item:

. . .
<!--Sample code showing usage of ApplicationBar-->
    <phone:PhoneApplicationPage.ApplicationBar>
        <shell:ApplicationBar IsVisible="True" IsMenuEnabled="True">
            <shell:ApplicationBarIconButton IconUri="/images/dark/appbar.new.rest.jpg"
            Text="new" Click="ApplicationBarIconNewButton_Click" x:Name="btnNew" />
            <shell:ApplicationBarIconButton
            IconUri="/images/dark/appbar.transport.play.rest.jpg"
            Text="start" IsEnabled="False" Click="ApplicationBarIconPlayButton_Click"
            x:Name="btnPlay"/>
            <shell:ApplicationBarIconButton IconUri="/images/dark/appbar.edit.rest.jpg"
            Text="edit" IsEnabled="False" Click="ApplicationBarIconEditButton_Click"
            x:Name="btnEdit"/>
            <shell:ApplicationBarIconButton IconUri="/images/dark/appbar.delete.rest.jpg"
            Text="delete" IsEnabled="False" Click="ApplicationBarIconDeleteButton_Click"
            x:Name="btnDelete"/>

            <shell:ApplicationBar.MenuItems>

					  

<shell:ApplicationBarMenuItem Text="Exercise of the day"
                 Click="ApplicationBarMenuItem_Click"/>
            </shell:ApplicationBar.MenuItems>
        </shell:ApplicationBar>
    </phone:PhoneApplicationPage.ApplicationBar>
. . .

In the Training.xaml.cs code, you use the constructor to map application bar buttons to related names so you can use variables to manage the buttons' properties throughout the entire code. The Buttons collection indexes correspond to the order you specified the buttons in the XAML code. So, the first New button will have the 0 index, the Play button will have the 1 index, and so on:

public partial class Training : PhoneApplicationPage
    {
        public Training()
        {
            InitializeComponent();
            btnNew = ApplicationBar.Buttons[0] as ApplicationBarIconButton;
            btnPlay = ApplicationBar.Buttons[1] as ApplicationBarIconButton;
            btnEdit = ApplicationBar.Buttons[2] as ApplicationBarIconButton;
            btnDelete = ApplicationBar.Buttons[3] as ApplicationBarIconButton;
        }
. . .

					  

Finally, you can use the buttons' names in other methods such as the lbExercise_SelectionChanged event handler that is raised when the user select an exercise from the list box. This event handler either enables or disables application bar buttons:

private void lbExercise_SelectionChanged(object sender,
                                                 SelectionChangedEventArgs e)
        {
            if (lbExercise.SelectedItems.Count > 0)
            {
                btnPlay.IsEnabled = true;
                btnEdit.IsEnabled = true;
                btnDelete.IsEnabled = true;
            }
            else
            {
                btnPlay.IsEnabled = false;
                btnEdit.IsEnabled = false;
                btnDelete.IsEnabled = false;
            }
        }

					  

5. Usage

In Visual Studio 2010, load the 7Drum project from the companion code and then press Ctrl+F5. If your target output is the Windows Phone 7 Emulator, you will see it running briefly. Tap the Training menu so that you go to the Training page shown in Figure 2. At the bottom of the screen, you can see the application bar with the Add button enabled and the others disabled.

Figure 2. The application bar contains four buttons, but only one is enabled.

Clicking the ellipses button at the top-right corner of the application bar causes the button descriptions and the menu items to appear (see Figure 3).

Figure 3. Clicking the ellipses button the application bar shows the buttons' text and menu items.